Clarify models vs callbacks in entry completion docs

See https://bugzilla.gnome.org/show_bug.cgi?id=641073

diff --git a/gtk/gtkentrycompletion.c b/gtk/gtkentrycompletion.c
index 763b670992068a9bdde6418cad04997c1dc9eb10..b770fa973ca80dd5661845a012eff579e3677c7c 100644 (file)
--- a/gtk/gtkentrycompletion.c
+++ b/gtk/gtkentrycompletion.c
@@ -49,6 +49,19 @@
  * "actions" in the popup window. Their appearance is similar to menuitems,
  * to differentiate them clearly from completion strings. When an action is
  * selected, the #GtkEntryCompletion::action-activated signal is emitted.
+ *
+ * GtkEntryCompletion uses a #GtkTreeModelFilter model to represent the
+ * subset of the entire model that is currently matching. While the
+ * GtkEntryCompletion signals #GtkEntryCompletion::match-selected and
+ * #GtkEntryCompletion::cursor-on-match take the original model and an
+ * iter pointing to that model as arguments, other callbacks and signals
+ * (such as #GtkCellLayoutDataFuncs or #GtkCellArea::apply-attributes)
+ * will generally take the filter model as argument. As long as you are
+ * only calling gtk_tree_model_get(), this will make no difference to
+ * you. If for some reason, you need the original model, use
+ * gtk_tree_model_filter_get_model(). Don't forget to use
+ * gtk_tree_model_filter_convert_iter_to_child_iter() to obtain a
+ * matching iter.
  */
 
 #include "config.h"
@@ -235,6 +248,9 @@ gtk_entry_completion_class_init (GtkEntryCompletionClass *klass)
    * entry with the contents of the text column in the row
    * pointed to by @iter.
    *
+   * Note that @model is the model that was passed to
+   * gtk_entry_completion_set_model().
+   *
    * Return value: %TRUE if the signal has been handled
    *
    * Since: 2.4
@@ -261,6 +277,9 @@ gtk_entry_completion_class_init (GtkEntryCompletionClass *klass)
    * of the entry with the contents of the text column in the row
    * pointed to by @iter.
    *
+   * Note that @model is the model that was passed to
+   * gtk_entry_completion_set_model().
+   *
    * Return value: %TRUE if the signal has been handled
    *
    * Since: 2.12